home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 20 / Cream of the Crop 20 (Terry Blount) (1996).iso / os2 / xdsn217.zip / DOC / xlib.txt < prev   
Text File  |  1996-07-10  |  13KB  |  381 lines
  1. xlib.txt                        Copyright (c) 1995,96 xTech Ltd
  2. ----------------------------------------------------------------
  3.  
  4.                       XDS Library Manager
  5.                       -------------------
  6.  
  7. Libraries are files of a special format that are used to collect
  8. object modules or information required to tune import from DLL
  9. (so called "import libraries").
  10.  
  11. The XLIB.EXE utility included to this package is intended for
  12. library management.
  13.  
  14. The following topics are discussed below:
  15.  
  16. 1. Usage
  17.    1.1 Options
  18.    1.2 File Names
  19.    1.3 Response files
  20.    1.4 Commands
  21.  
  22. 2. Operation modes
  23.  
  24. 3. Proper librarian mode
  25.  
  26. 4. Import Librarian Mode
  27.  
  28. 5. Library Contents List Mode
  29.  
  30. 6. Supported Formats
  31.    6.1. Output library format
  32.    6.2. Input object file format
  33.    6.3. Input executable format
  34.    6.4. Import Definition Files Format
  35.  
  36. 1. Usage
  37. --------
  38.  
  39. To invoke XDS Library manager enter a command "xlib" with
  40. necessary arguments. Being invoked without additional arguments
  41. xlib outputs a brief help message similar to the following:
  42.  
  43.   XDS Library manager v1.0 (c) xTech 1995
  44.   usage   = xlib /IMPLIB { option } libname[.lib] { file }
  45.           | xlib { option } libname[.lib] { command }
  46.           | xlib /LIST { option } libname[.lib]
  47.   option  = /OptionName[+|-|=ValueString]
  48.   file    = filename([.dll]|.exe|.idf) | @ResponceFileName
  49.   command = { +|-|* }module[.obj] | @ResponceFileName
  50.     "+" - add module to library
  51.     "-" - remove module from library
  52.     "*" - extract module to separate object file
  53.   Options:
  54.     /IMPLIB - create import library
  55.     /LIST   - show library contens
  56.     /LOGO-  - no logo
  57.     /HELP   - print this text
  58.     /SAFE-  - no "BAK" files
  59.     /NEW    - create new library file (without /LIST and /IMPLIB
  60.               only)
  61.     /PREFIX=str  - set internal name prefix to "str"
  62.                    (with /IMPLIB only)
  63.     /POSTFIX=str - set internal name postfix to "str"
  64.                    (with /IMPLIB only)
  65.  
  66.  
  67. An argument may be either an option, a file name, a command, or 
  68. a response file. Arguments controls operation mode, name of output
  69. library and a set of files used to perform requested task.
  70.  
  71.  
  72. 1.1 Options
  73.  
  74. Options may be placed in arbitrary order at the command line.
  75. Options are started with the slash ("/") character immediately
  76. followed by an option name and optionally with ON/OFF sign
  77. ("+"/"-") or with the "=" sign followed by a string value.
  78. In the first case the option is of BOOLEAN type while in the 
  79. latter case it have a string value. Types of valid options
  80. are hard-coded in the program and improper type of an option 
  81. would cause an error. If neither "+", "-", or "=<string>" is present,
  82. the option is considered to be of BOOLEAN type with value "ON".
  83.  
  84. Following is a list of all valid options with their meaning and
  85. default values.
  86.  
  87. ===============================================================
  88. Name    Type  Default  Effect
  89.                value
  90. ---------------------------------------------------------------
  91. IMPLIB  BOOL   OFF     Set xlib to "import librarian" mode
  92.                        of operation (See 4)
  93.  
  94. LIST    BOOL   OFF     If ON, xLib only outputs contents of
  95.                        a given library; no other operation is
  96.                        performed. (See 5)
  97.  
  98. LOGO    BOOL   ON      Specifies whether xLib has to print its
  99.                        logo.
  100.  
  101. HELP    BOOL   OFF     If ON, causes  xLib to output a brief 
  102.                        help text; no other operation is be
  103.                        performed.
  104.  
  105. SAFE    BOOL   ON      Sets the xlib to rename files to ".BAK"
  106.                        before overwriting them.
  107.  
  108. NEW     BOOL   OFF     xlib will always create a new library file
  109.                        instead of using the existing one.
  110.  
  111. PREFIX  Str    empty   Sets prefix of imported names 
  112.                        (See 4).
  113.  
  114. POSTFIX Str    empty   Sets postfix of imported names 
  115.                        (See 4).
  116.  
  117. ===============================================================
  118.  
  119. If xlib encounters an unknown option, or an option that have no
  120. effect in a given operation mode, it produces a warning message.
  121.  
  122.  
  123. 1.2 File Names
  124.  
  125. File names appearing in xlib's command line are regular file
  126. names. Each name may be prefixed with directory path.
  127. If extension is omitted defaults are used. Below is the
  128. list of default extensions for various types of files.
  129.  
  130. Type            Extension
  131.  
  132. Library file     .lib
  133. Object module    .obj
  134. DLL              .dll
  135.  
  136. 1.3 Response files
  137.  
  138. Response file for xlib is a text file that contains a number
  139. of xlib arguments, one per line. Any kind of argument is allowed
  140. except response file. Some options have no effect when used 
  141. in response file, These are "IMPLIB", "LIST", "HELP" and "LOGO"
  142. options.
  143.  
  144. 1.4 Commands
  145.  
  146. Commands are names of files prefixed by a set of command
  147. signs. The signs are "+","-" and "*". Any other character used
  148. in a command prefix is interpreted as first character of a proper
  149. file name. Relational order of characters in the prefix have no
  150. meaning.
  151.  
  152. Note that commands are valid for "library manager" operation
  153. mode only (See 3).
  154.  
  155.  
  156. 2. Operation modes
  157. ------------------
  158.  
  159. The xlib utility has three operation modes: library contents
  160. list mode, import librarian mode and proper librarian
  161. mode. Operation modes are switched by "IMPLIB" and "LIST"
  162. options as follows:
  163.  
  164.   i)   If "IMPLIB" option is set, xlib is switched to import
  165.   librarian mode (See 4).
  166.  
  167.   ii)  If "LIST" option is set, xlib is switched to library
  168.   contents list mode (See 5).
  169.  
  170.   iii) If both "IMPLIB" and "LIST" options are set, xlib is
  171.   switched to import librarian mode (See 4).
  172.  
  173.   iv)  If both "IMPLIB" and "LIST" modes are not set, xlib is
  174.   switched to proper librarian mode (See 3).
  175.  
  176. Details of operation modes are given in following chapters.
  177.  
  178.  
  179. 3. Proper librarian mode
  180. ------------------------
  181.  
  182. In this mode xlib acts as a proper library manager. First given
  183. argument that does not represent an option setting is treated as
  184. a name of a library file to deal with. If extension is omitted, the
  185. default ".lib" is added. If the option "NEW" is not set, the
  186. xlib supposes that the given library file should exist and should
  187. be valid, otherwise it produces a warning and createsa a new
  188. library file.
  189.  
  190. Other arguments given in the command line or in a response file are
  191. treated as commands (see 1.4). Each command represents a set
  192. of actions and a name of object module or library.
  193.  
  194. Valid actions are add, remove and extract. The are denoted by
  195. "+", "-" and "*" characters respectively. When more than one 
  196. action is specified, xlib performs them in following order:
  197.  
  198.    1) extract
  199.    2) remove
  200.    3) add
  201.  
  202. For instance, to replace module "a.obj" you may use either "-+a" or
  203. "+-a".
  204.  
  205. If all commands are successfully executed, xlib checks the resulting
  206. library for duplicate names, producing warnings if necessary.
  207.  
  208. Then xlib creates an output library file and writes the
  209. resulting library. If any file with name equal to output file
  210. name does already exist then xlib may save it by changing its
  211. extension to ".BAK" before overwrite. It is controlled by the SAFE
  212. option that is set ON by default.
  213.  
  214.  
  215. 4. Import Librarian Mode
  216. ------------------------
  217.  
  218. In this mode xlib produces special kind of library - so called
  219. "import library". This kind of libraries contain the information
  220. for a linker on how to tune up import information in the target
  221. executable. Import libraries are commonly used instead of
  222. definition files.
  223.  
  224. To switch xlib to import librarian mode set the "IMPLIB"
  225. option ON (i.e. use "/IMPLIB" or "/IMPLIB+" string in the
  226. command line).
  227.  
  228. In this mode xlib treats first given argument that does not
  229. represent an option setting as a name of an output library file.
  230. If extension is omitted, default ".lib" is added. xlib
  231. always creates new file for the resulting library. If a file
  232. with a given name does already exist, xlib may save it by
  233. changing its extension to ".BAK" depending on "SAFE" option
  234. setting.
  235.  
  236. Other arguments that